Lose Developers and Alienate Everyone: How Not to Write Docs

Published Dec 13, 2019 by Alex C-G

You know, there are so many projects out there with great documentation. To make your docs stand out, why not make them crappy instead? Just think of the buzz you’ll get on Twitter and all the questions on Stack Overflow trying to find out what anything means! And who needs GitHub Stars when you have an issue queue filling up with basic questions?

So, without further ado, let’s Think Different, Be What’s Next, and Disrupt your Docs!

Note: The tales of woe below are all true. I’ve personally experienced them…and worse.

1. Sesquipedalian Loquaciousness

Your team has put so much effort into developing its own jargon and slang. Sure, some may say it looks like buzzword bingo or an explosion in a dictionary factory, but what do they know? They wouldn’t appreciate your Sesquipedalian Loquaciousness if it bit them on the nose.

Thanks to SMBC for the comic!

Your long words and purple prose ensure everyone can see how smart you and your development team are, and with such an intelligent team they’re bound to want to use your code!

Seriously though… Not all of the folks reading (or contributing to) your docs will be native speakers of your language. And what are people more likely to Google? projectname API or projectname meta synergy protocol?

2. Mark Down? Who’s He?

Everyone should be free to use the authoring tool of their choice. After all, what’s the point in Free Software if you don’t have the freedom to write your docs in Scrivener, Apple Pages, Microsoft Word, or PowerPoint. As long as they get the files onto Github it’s all good!

Or why not try Lotus Word Pro?

Seriously though… I’ve had to deal with Apple Pages files being uploaded onto repo’s before, and that’s by members of the internal dev team. Using a Linux box, they’re a pain in the neck to open, and how the hell are you going to do version control on those things? That’s not to mention the time a junior dev uploaded Markdown pasted into a Word file, which they then renamed to have an .md extension…

3. Yeet those 🗎 and smash that “Clone or download” button, fam 😎

Your project is cutting edge, so your docs should reflect that. No need for any of that frumpy old English - Emojis work across languages and have no ambiguity, and if you want to attract a cool, hepcat group of rockstar ninja hackers you need to speak their language. Not employing any 13 year olds? Just ask your niece to yeet something up for you! And don’t forget those amazeballs acronyms LOL!

Yes, that’s exactly what it means…

Seriously though… Don’t. Just don’t. Nobody hits up your developer docs to be entertained. And many devs are terminal jockeys, and emoji’s don’t translate well to that environment.

4. A Thousand Eyes Make All Docs Perfect

Your docs are the lifeblood for your ecosystem of developers. And nobody wants dirty blood, do they? Best to have your team of experts check everything three or four times before uploading, and then get final approval from the CEO before opening your docs repo. Developers won’t mind waiting a few weeks (or months) for a basic API reference as long as every T is crossed and every I dotted.

Seriously though… The perfect is the enemy of the good, and there are a lot of good projects out there catching the eyes of developers. Release early, and release often. It’s better to have some basic docs out there that do the job, rather than a perfect all-singing, all-dancing ensemble that’s already out-of-date by the time its released.

5. If You Truly Loved Me, You’d Put the Work in…

You don’t want just anyone contributing to your project or using your tools. Only the best are good enough - and your application and vetting process ensures that only the best applicants will get that coveted repo access…any day now. Be sure to ask them for their LinkedIn profile (so you can see they’re a true professional), their phone number (because data leaks and phishing aren’t a thing), and a convoluted password (because those docs are precious, damnit)

Seriously though… Developers are typically looking at several ways to get the job done, and adding friction will just push them elsewhere, regardless of how great your project is.

Next Time

In the next post we’ll be looking at best (and worst) practices for documentation platforms. Stay tuned!